home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD 2.1 / Amiga Developer CD v2.1.iso / NDK / NDK_3.5 / Tutorials / ARexx / Host / Hosts_and_Clients.doc < prev    next >
Encoding:
Text File  |  1996-02-27  |  4.7 KB  |  95 lines
  1. AREXX HOSTS AND CLIENTS
  2. =======================
  3. The built-in ARexx command set can be extended through so-called function
  4. hosts. ARexx knows two built-in hosts, one being "REXX", the other
  5. "COMMAND". "REXX" is the host every program talks to when it is started.
  6. "COMMAND" interpretes the commands it receives as the names of AmigaDOS
  7. commands it should launch. Every command that is not part of the Rexx
  8. language will be sent to the host which has to decide whether it understands
  9. the command or not.
  10.  
  11.  
  12. ARexx host design
  13. -----------------
  14. Hosts are basically message ports which can be found in the public message
  15. port list. The port names must be unique and consist of upper case
  16. alphanumeric characters and the dot "." and bar "_" characters only and
  17. should be less than 20 characters long. ARexx itself does not enforce this
  18. naming scheme, but for the sake of the user you should follow it where
  19. possible. If the name contains lower case of space characters the user
  20. would have to enclose the host name in quotes. Long names can be a nuisance
  21. if one has to type them over and over again.
  22.  
  23. Messages sent from Rexx are special in that a function IsRexxMsg() exists
  24. which can tell Rexx messages and messages of a different type apart. Thus,
  25. you could use one single message port for your program communications and
  26. respond to the messages you receive from it according to what IsRexxMsg()
  27. tells you what type they are.
  28.  
  29. Each RexxMsg your program receives through the host port carries the
  30. command to execute and command arguments in RexxMsg->rm_Args[0] as a
  31. pointer to a null-terminated string. The command and arguments are
  32. separated by space or tab characters. Your program must decide whether it
  33. understands this command or not and act accordingly.
  34.  
  35.     NOTES: When deciding whether a command is supported by your
  36.            host implementation, use a CASE-INSENSITIVE comparison
  37.            as you cannot make any assumptions on whether the command
  38.            will consist of lower case, upper case or mixed case
  39.            characters.
  40.  
  41.            Keep in mind that the string you find in RexxMsg->rm_Args[0]
  42.            contains both the name of the command AND its arguments.
  43.            Your program must first extract the command name before it
  44.            can compare it with the supported host commands.
  45.  
  46.            Except for the RexxMsg->rm_Result1 and RexxMsg->rm_Result2
  47.            entries the entire RexxMsg structure is READ-ONLY.
  48.  
  49.  
  50. Command line parsing
  51. --------------------
  52. One way to turn the arguments following the command into useable data is to
  53. take advantage of the dos.library/ReadArgs routine. This system call parses
  54. the arguments by matching them against a given template and stores the
  55. information it collects from the arguments in a data table your host
  56. commands can refer to. This works well, but there is a catch: commands which
  57. require quotes become more complex due to how ARexx and and ReadArgs()
  58. interact. The following table illustrates how Rexx transforms command lines
  59. before it passes them to the host:
  60.  
  61.        Rexx script line reads   Host receives
  62.        ======================   ===============
  63.        open "old file"          OPEN old file
  64.        "open old file"          open old file
  65.        open '"old file"'        OPEN "old file"
  66.  
  67. Thus, the outermost quotes will get removed before ARexx passes
  68. the command line to the host.
  69.  
  70.  
  71. Host errors and results
  72. -----------------------
  73. If the host must return an error or issue a warning it can do so by using
  74. the RexxMsg->rm_Result1 entry. The value you place here will affect the
  75. contents of the "RC" variable Rexx maintains. Typically, a value of 10 or
  76. higher will cause the Rexx program that called your host function to stop.
  77.  
  78. The value of RexxMsg->rm_Result1 will tell the Rexx program that an error
  79. occured or a warning status was set, but it will not know which kind of
  80. error has occured. RexxMsg->rm_Result2 cannot be be used to convey the
  81. error type as Rexx will ignore this field if RexxMsg->rm_Result1 is nonzero.
  82. One way to solve this problem is to set a variable of the Rexx program to
  83. call host through the amiga.lib/SetRexxVar routine. The Rexx program can
  84. then examine the "RC" variable to check whether an error has occured and
  85. look at the contents of this variable to determine the type of error.
  86. A good choice for this variable would be "<Host name>.LASTERROR" with
  87. <Host name> being the name of the host that flagged the error.
  88.  
  89.  
  90. Successful execution of a command is indicated by placing a value of
  91. 0 both in RexxMsg->rm_Result1 and RexxMsg->rm_Result2. If your command can
  92. return a result you should examine the RexxMsg->rm_Action field. If the
  93. bit RXFB_RESULT is set it indicates that the Rexx program to call your host
  94. wants to see a command result, if possible.
  95.